@hoardodile/create-plugin 0.1.3 → 0.1.5

package/dist/template/.github/workflows/release.yml

@@ -43,12 +43,15 @@ jobs:
       - name: Package the release artifacts
         run: pnpm exec hoardodile plugin package --skip-build
 
+      - name: Gate the introduction (intro/ must be flat, images by bare filename)
+        run: pnpm intro:check
+
       - name: Publish the GitHub release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           files=$(ls release/*)
-          if ls intro.*.md >/dev/null 2>&1; then
-            files="$files intro.*.md"
+          if [ -d intro ]; then
+            files="$files intro/*"
           fi
           gh release create "$GITHUB_REF_NAME" $files --generate-notes

package/dist/template/README.md

@@ -100,13 +100,34 @@ private packages.
 ## Publishing an introduction
 
 The marketplace detail view shows a per-release **Intro** tab. Ship one
-markdown file per supported language at the repository root, named
-`intro.<locale>.md` (e.g. `intro.en.md`, `intro.zh.md`) — `release.yml`
-uploads them alongside the zip, so **each release carries its own
-introduction** and every version shows independent notes. Use the app's
-supported language codes as file names (`en`, `zh`, `ja`, `de`, `es`) —
-a region-coded name like `intro.zh-CN.md` only matches a UI language
-resolved to that exact code, so `intro.zh.md` is what Chinese users see.
+markdown file per supported language inside the **`intro/` folder**, named
+`intro.<locale>.md` (e.g. `intro/intro.en.md`, `intro/intro.zh.md`) —
+`release.yml` uploads the whole folder alongside the zip, so **each release
+carries its own introduction** and every version shows independent notes.
+Use the app's supported language codes as file names (`en`, `zh`, `ja`,
+`de`, `es`) — a region-coded name like `intro.zh-CN.md` only matches a UI
+language resolved to that exact code, so `intro.zh.md` is what Chinese
+users see.
+
+### Adding images
+
+An introduction may reference images. Place the image in `intro/` and
+reference it by its **bare filename**:
+
+```md
+![Plugin screenshot](screenshot.png)
+```
+
+Every file in `intro/` is published as a release asset on each release, and
+the app resolves a relative image reference against that release's download
+URL. Because a GitHub release is a flat list of assets, the `intro/` folder
+must stay **flat** and references must be bare filenames — a nested path
+like `![alt](img/shot.png)` resolves to a URL the release does not serve and
+the image breaks. Absolute `http(s)://` and `data:` image URIs are allowed.
+
+`pnpm intro:check` (run by `release.yml` before publishing) gates this: it
+fails the release if `intro/` is absent-and-required, is not flat, ships no
+`intro.<locale>.md`, or references an image by a nested/missing path.
 
 The app resolves the intro for the user's UI language (exact locale → base
 language → `en` → the only shipped language); the release body always shows

package/dist/template/package.json

@@ -11,6 +11,7 @@
 		"detect:smoke": "hoardodile plugin run detect testdata --plugin-dir dist",
 		"lint": "tsc --noEmit",
 		"test": "vitest run",
+		"intro:check": "node scripts/check-intro.mjs",
 		"release": "node scripts/release.mjs"
 	},
 	"release-it": {

package/dist/template/scripts/check-intro.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Release gate for the plugin marketplace introduction images.
+ *
+ * The marketplace reads each release's `intro.<locale>.md` asset and the
+ * app resolves any image referenced inside it against the release's
+ * download URL. Because a GitHub release is a flat list of assets, every
+ * referenced image must be:
+ *
+ *   1. Shipped inside the `intro/` folder (the only folder the release
+ *      workflow uploads), and
+ *   2. Referenced by its bare filename (`![alt](shot.png)`), never a
+ *      nested path (`img/shot.png`) — a nested path resolves to a URL the
+ *      release does not actually serve, so the image is silently broken.
+ *
+ * This gate fails a build/release when the `intro/` folder is absent, is
+ * not flat, ships no `intro.<locale>.md`, or references an image by a
+ * nested/missing path. External `http(s)://` and `data:` image URIs are
+ * allowed (they are not release assets).
+ *
+ * Usage:
+ *   node scripts/check-intro.mjs            # checks ./intro
+ *   node scripts/check-intro.mjs <dir>      # checks <dir>/intro
+ *
+ * Dependency-free on purpose — it ships inside every scaffolded plugin.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+const ROOT = resolve(process.argv[2] ?? process.cwd())
+const INTRO_DIR = join(ROOT, "intro")
+
+const RULE_SUMMARY =
+	"intro/ must be flat; each intro.<locale>.md image is referenced by a " +
+	"bare filename that exists in intro/ (absolute http(s)/data URIs are ok)"
+
+// `![alt](src)`, `![alt](src "title")`, `<img src="x">` (`src` images only).
+const MARKDOWN_IMG_RE = /!\[[^\]]*\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g
+const HTML_IMG_RE = /<img\b[^>]*\bsrc\s*=\s*(["'])([^"']+)\1/gi
+const EXT_URL_RE = /^(?:https?:\/\/|data:)/i
+
+function isRelative(src) {
+	return !EXT_URL_RE.test(src)
+}
+
+/**
+ * A relative reference is valid only as a flat bare filename that exists
+ * inside `intro/` — not a nested path and not a missing/unshipsed file.
+ */
+function resolveRelativeRef(src, file, issues) {
+	const trimmed = src.trim().replace(/^\.\//, "")
+	if (trimmed.length === 0) {
+		issues.push(`${file}: empty image reference`)
+		return
+	}
+	if (
+		trimmed.includes("/") ||
+		trimmed.includes("\\") ||
+		trimmed.includes("..")
+	) {
+		issues.push(
+			`${file}: image "${src}" is not flat — use a bare filename like "shot.png" (release assets are flat)`,
+		)
+		return
+	}
+	const target = join(INTRO_DIR, trimmed)
+	if (!existsSync(target) || !statSync(target).isFile()) {
+		issues.push(
+			`${file}: image "${src}" is not in intro/ — every referenced image must be committed there (it is published with the release)`,
+		)
+	}
+}
+
+function collectImageRefs(text) {
+	const refs = []
+	for (const match of text.matchAll(MARKDOWN_IMG_RE)) refs.push(match[1])
+	for (const match of text.matchAll(HTML_IMG_RE)) refs.push(match[2])
+	return refs
+}
+
+function main() {
+	if (!existsSync(INTRO_DIR)) {
+		console.log(
+			"[check-intro] no intro/ folder — nothing to gate (a release without an introduction is valid).",
+		)
+		return
+	}
+
+	const entries = readdirSync(INTRO_DIR, { withFileTypes: true })
+	const issues = []
+
+	// 1. Flat-only: any subdirectory makes the folder publish incorrectly.
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			issues.push(
+				`intro/${entry.name}/ is a subdirectory — the intro folder must be flat (release assets are a flat list)`,
+			)
+		}
+	}
+
+	const mdFiles = entries
+		.filter(
+			(entry) =>
+				entry.isFile() && /^intro\.[A-Za-z0-9-]+\.md$/.test(entry.name),
+		)
+		.map((entry) => entry.name)
+
+	if (mdFiles.length === 0) {
+		issues.push(
+			"intro/ has no intro.<locale>.md — the release would ship images but the marketplace could not display an introduction",
+		)
+	}
+
+	// 2. Flat, present image references inside each intro markdown.
+	for (const name of mdFiles) {
+		const text = readFileSync(join(INTRO_DIR, name), "utf-8")
+		for (const src of collectImageRefs(text)) {
+			if (isRelative(src)) resolveRelativeRef(src, `intro/${name}`, issues)
+		}
+	}
+
+	if (issues.length > 0) {
+		console.error("[check-intro] gate failed:")
+		for (const issue of issues) console.error(`  - ${issue}`)
+		console.error(`\n${RULE_SUMMARY}`)
+		process.exit(1)
+	}
+
+	console.log(
+		`[check-intro] intro/ ok — ${mdFiles.length} introduction file(s), flat references only.`,
+	)
+}
+
+main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoardodile/create-plugin",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "license": "MIT",
   "description": "Scaffold a hoardodile content plugin.",
   "keywords": [
@@ -37,7 +37,7 @@
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "zod": "^4.4.3",
-    "@hoardodile/sdk-types": "0.1.3"
+    "@hoardodile/sdk-types": "0.1.5"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",